Skip to content

fix(export): give VideoToolbox exports a two-second keyframe interval - #2502

Merged
richiemcilroy merged 2 commits into
mainfrom
perf/videotoolbox-export-keyframes
Oct 14, 2026
Merged

richiemcilroy merged 2 commits into
mainfrom
perf/videotoolbox-export-keyframes

Conversation

@richiemcilroy

@richiemcilroy richiemcilroy commented Oct 13, 2026 •

Copy link
Copy Markdown
Member

On macOS, every MP4 export inserts a keyframe every 12 frames. The h264_videotoolbox export branch of get_codec_and_options (crates/enc-ffmpeg/src/video/h264.rs) never sets g, so FFmpeg's default GOP of 12 applies. Every other encoder branch sets g to DEFAULT_KEYFRAME_INTERVAL_SECS (2 s), and the export size estimate assumes that 2 s GOP too.

"h264_videotoolbox" => {
    if is_export {
        options.set("realtime", "false");
        options.set("profile", "main");
        options.set("allow_sw", "0");
        options.set("g", &keyframe_interval_str); // new: 2 s, e.g. 120 at 60 fps
    } else {
        // realtime (recording) options unchanged
    }
}
flowchart LR
  subgraph Before["Before: GOP 12 (5 I-frames/s at 60 fps)"]
    direction LR
    I1[I] --> P1[P x11] --> I2[I] --> P2[P x11] --> I3[I] --> P3[...]
  end
  subgraph After["After: GOP 120 (one I-frame per 2 s)"]
    direction LR
    J1[I] --> Q1[P x119] --> J2[I] --> Q2[...]
  end
Loading
  • At 60 fps that is 5 I-frames per second. VideoToolbox overshoots the target bitrate to pay for them, so exports come out up to 3x larger than the bitrate Cap asks for, without better quality.
  • The fix sets the export keyframe interval to the same 2 s every other encoder uses. Recording (realtime) options are unchanged, so fragmented recording and Instant segment cuts are not affected.
  • videotoolbox_export_uses_the_default_keyframe_interval checks that the export options carry g = 120 at 60 fps and that the realtime options still don't set g.

Size and quality

M4 Max, cap export --fps 60. Two fixtures recorded with the cap CLI from main:

  • studio-cam: 60 s Studio recording, 3024x1964 display with a looping screen video, 720p camera, mic and system audio.
  • scroll: 30 s Studio recording, 3024x1964 at 60 fps of a page scrolling at 1500 px/s with a video overlay. This is the worst case for long GOPs.

Quality is measured against a reference export of the same project at 2-3 bpp.

Fixture Preset Keyframes main → PR Size main Size PR PSNR main → PR XPSNR-Y main → PR
studio-cam 1080p Maximum 300 → 30 49.0 MB 15.8 MB 54.04 → 54.09 dB 49.18 → 49.17 dB
studio-cam 1080p Potato 300 → 30 26.9 MB 6.6 MB 46.40 → 47.84 dB
scroll 1080p Maximum 150 → 15 94.5 MB 81.5 MB 54.52 → 54.51 dB 52.39 → 52.44 dB
scroll 1080p Social 150 → 15 48.6 MB 45.1 MB 50.39 → 51.26 dB 48.17 → 49.03 dB
scroll 1080p Potato 150 → 15 13.0 MB 13.0 MB 41.48 → 44.69 dB
studio-cam 4K Maximum 300 → 30 93.0 MB 30.0 MB
scroll 4K Maximum 150 → 15 168.4 MB 144.1 MB
  • At Maximum, quality is unchanged (within ±0.05 dB) and files are 14-68% smaller.
  • At lower presets, files are the same size or smaller and quality is clearly higher (up to +3.2 dB PSNR on the scrolling worst case).
  • The 1080p studio-cam export takes 11.95 s instead of 12.59 s, since the encoder writes fewer I-frames.

RetriggerConfidence Score: 5/5

The PR appears safe to merge; the previous test failure is fixed.

Summary

Sets a two-second keyframe interval for VideoToolbox exports. Recording options stay unchanged.

  • VideoToolbox exports use a two-second keyframe interval.

Reviews (2) · Last reviewed commit: "test(enc-ffmpeg): skip the VideoToolbox ..." · Reviewed by Greptile

@vercel

vercel Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
cap-status Ready Ready Preview Oct 13, 2026 5:34pm UTC

@capy-ai capy-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Capy found no issues.

View 1 other finding in Capy.

Open in Capy

Comment thread crates/enc-ffmpeg/src/video/h264.rs Resolved
@richiemcilroy

Copy link
Copy Markdown
Member Author

hey @greptileai, please re-review the PR

@capy-ai capy-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Capy found no issues.

Open in Capy

@richiemcilroy
richiemcilroy merged commit 2c7da2b into main Oct 14, 2026
32 checks passed

This branch was successfully deployed

2 active deployments
Preview – cap-web — 840b3fae Deployed Oct 13, 2026 by vercel[bot]
Preview – cap-status — 840b3fae Deployed Oct 13, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant